<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">















 
 
 
 
 
 
 
  
  


<html>
  <head>
    <script type="text/javascript" language="JavaScript">
    ORIGINAL_PAGE_PATH = "/appengine/docs/python/datastore/modelclass.html";
    </script>
    
    
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>The Model Class - Google App Engine - Google Code</title>
<script type="text/javascript"><!--
(function(){function a(){this.t={};this.tick=function(c){this.t[c]=(new Date).getTime()};this.tick("start")}var b=new a;window.jstiming={Timer:a,load:b};if(window.external&&window.external.pageT)window.jstiming.pt=window.external.pageT;})();

var _tocPath_ = '/appengine/docs/_toc.ezt';
var codesite_token = null;
//--></script>
<link href="../../../../css/codesite.pack.04102009.css" type="text/css" rel="stylesheet"></link>
<script src="../../../../js/codesite_head.pack.04102009.js" type="text/javascript"></script>
<script type="text/javascript">CODESITE_CSITimer['load'].tick('bhs');</script>
<link rel="search" type="application/opensearchdescription+xml" title="Google Code" href="http://code.google.com/osd.xml" />

<!--[if IE]><link rel="stylesheet" type="text/css" href="../../../../css/iehacks.css" /><![endif]-->

    <link href="../../../../css/semantic_headers.css" rel="stylesheet" type="text/css" />
    <link href="../../../css/local_extensions.css" rel="stylesheet" type="text/css" />
  </head>

  <body class="gc-documentation">

    
    
    
</a>

<div id="gb">
 <span>
  
    <a id="lang-dropdown" class="dropdown" href="http://code.google.com" onclick="return false;"><img class="globeicon" src="../../../../images/globe2_small.png"/><span>English</span></a>
  
 </span>
</div>

<div class="gbh" style="left: 0pt;"></div>
<div class="gbh" style="right: 0pt;"></div>


<style type="text/css">
  #gc-topnav h1 {
    padding: 0 0 0 6px;
  }
</style>


<div id="gc-container">
<a name="top"></a>
<div id="skipto">
  <a href="#gc-pagecontent">Skip to page content</a>
  <a href="#gc-toc">Skip to main navigation</a>
</div>

<div id="gc-header">
  <div id="logo"><a href="http://code.google.com">
  
  
     <img src="../../../../images/cleardot.gif" height="1px" width="1px" alt="Google Code Home Page" id="gc-logo-img"/>
  
  
  </a></div>
  <div id="search">
    <div id="searchForm" class="searchForm">
      <form id="cse" action="http://www.google.com/cse" accept-charset="utf-8" class="gsc-search-box" onsubmit="executeGSearch(document.getElementById('gsearchInput').value); return false;">
      <noscript>
      <input type="hidden" name="cref" value="http://code.google.com/cse/googlecode-context.xml"/>
      </noscript>
        <table class="gsc-search-box" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td class="gsc-input">
                <input id="gsearchInput" type="text" name="q" maxlength="2048" class="gsc-input" autocomplete="off" title="Google Code Search" style="width:345px"/>
              </td>
              <td class="gsc-search-button">
                <div id="cs-searchresults" onclick="event.cancelBubble = true;"></div>
                <input title="Search" id="gsearchButton" class="gsc-search-button" name="sa" value="Search" type="submit"/>
              </td>
            </tr>
            <tr>
              <td colspan="2" class="greytext">e.g. "templates" or "datastore"</td>
            </tr>
          </tbody>
        </table>
      </form>
    </div> <!-- end searchForm -->
  </div> <!-- end search -->
</div> <!-- end gc-header -->


<div id="codesiteContent">

<a name="gc-topnav-anchor"></a>
<div id="gc-topnav">
  <h1>Google App Engine</h1>
  <ul id="docs" class="gc-topnav-tabs">

    <li id="home_link">
      <a href="../../../index.html" title="Google App Engine home page">Home</a>
    </li>
  
    <li id="docs_link">
      <a href="../../index.html" class="selected" title="Official Google App Engine documentation">Docs</a>
    </li>
  
    <li id="faq_link">
      <a href="../../../kb/index.html" title="Answers to frequently asked questions about Google App Engine">FAQ</a>
    </li>
  
    <li id="articles_link">
      <a href="../../../articles/index.html" title="Focused articles and tutorials for Google App Engine developers">Articles</a>
    </li>
  
    <li>
      <a href="http://googleappengine.blogspot.com/" title="Official Google App Engine blog">Blog</a>
    </li>
  
    <li>
      <a href="../../../community.html" title="Community home for Google App Engine">Community</a>
    </li>
  
    <li>
      <a href="../../../terms.html" title="Google App Engine terms of service">Terms</a>
    </li>
  
    <li>
      <a href="../../../downloads.html" title="Download Google App Engine">Download</a>
    </li>
  

  </ul>
</div> <!-- end gc-topnav -->

    <div class="g-section g-tpl-170">

      <div class="g-unit g-first" id="gc-toc">
        <ul>
  <li><a href="../../../downloads.html">Downloads</a></li>
  <li><a href="http://code.google.com/status/appengine">System Status</a></li>
  <li><a href="http://code.google.com/p/googleappengine/issues/list">Issue Tracker</a></li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Getting Started</h2>
    <ul>
      <li><a href="../../whatisgoogleappengine.html">What Is Google App Engine?</a></li>
      <li><a href="../../java/gettingstarted/index.html">Java</a>
        <ul>
              <li><a href="../../java/gettingstarted/introduction.html">Introduction</a></li>
    <li><a href="../../java/gettingstarted/installing.html">Installing the Java SDK</a></li>
    <li><a href="../../java/gettingstarted/creating.html">Creating a Project</a></li>
    <li><a href="../../java/gettingstarted/usingusers.html">Using the Users Service</a></li>
    <li><a href="../../java/gettingstarted/usingjsps.html">Using JSPs</a></li>
    <li><a href="../../java/gettingstarted/usingdatastore.html">Using the Datastore with JDO</a></li>
    <li><a href="../../java/gettingstarted/staticfiles.html">Using Static Files</a></li>
    <li><a href="../../java/gettingstarted/uploading.html">Uploading Your Application</a></li>

        </ul>
      </li>
      <li><a href="../gettingstarted/index.html">Python</a>
        <ul>
            <li><a href="../gettingstarted/introduction.html">Introduction</a></li>
  <li><a href="../gettingstarted/devenvironment.html">The Development Environment</a></li>
  <li><a href="../gettingstarted/helloworld.html">Hello, World!</a></li>
  <li><a href="../gettingstarted/usingwebapp.html">Using the webapp Framework</a></li>
  <li><a href="../gettingstarted/usingusers.html">Using the Users Service</a></li>
  <li><a href="../gettingstarted/handlingforms.html">Handling Forms With webapp</a></li>
  <li><a href="../gettingstarted/usingdatastore.html">Using the Datastore</a></li>
  <li><a href="../gettingstarted/templates.html">Using Templates</a></li>
  <li><a href="../gettingstarted/staticfiles.html">Using Static Files</a></li>
  <li><a href="../gettingstarted/uploading.html">Uploading Your Application</a></li>

        </ul>
      </li>
    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Java <sup class="new">Early Look</sup></h2>
    <ul>
          <li><a href="../../java/overview.html">Overview</a></li>
    <li><a href="../../java/runtime.html">Servlet Environment</a></li>
    <li><a href="../../java/datastore/index.html">Storing Data</a>
      <ul>
            <li><a href="../../java/datastore/overview.html">Overview</a></li>
    <li><a href="../../java/datastore/usingjdo.html">Using JDO</a></li>
    <li><a href="../../java/datastore/dataclasses.html">Defining Data Classes</a></li>
    <li><a href="../../java/datastore/creatinggettinganddeletingdata.html">Creating, Getting and Deleting Data</a></li>
    <li><a href="../../java/datastore/queriesandindexes.html">Queries and Indexes</a></li>
    <li><a href="../../java/datastore/transactions.html">Transactions</a></li>
    <li><a href="../../java/datastore/relationships.html">Relationships</a></li>
    <li><a href="../../java/datastore/usingjpa.html">Using JPA</a></li>
    <li><a href="../../java/javadoc/com/google/appengine/api/datastore/package-summary.html">Low-level API</a></li>

      </ul>
    </li>
    <li><a href="../../java/apis.html">Services</a>
      <ul>
        <li><a href="../../java/memcache/index.html">Memcache</a>
          <ul>
                <li><a href="../../java/memcache/overview.html">Overview</a></li>
    <li><a href="../../java/memcache/usingjcache.html">Using JCache</a></li>
    <li><a href="../../java/javadoc/com/google/appengine/api/memcache/package-summary.html">Low-level API</a></li>

          </ul>
        </li>
        <li><a href="../../java/urlfetch/index.html">URL Fetch</a>
          <ul>
                <li><a href="../../java/urlfetch/overview.html">Overview</a></li>
    <li><a href="../../java/urlfetch/usingjavanet.html">Using java.net</a></li>
    <li><a href="../../java/javadoc/com/google/appengine/api/urlfetch/package-summary.html">Low-level API</a></li>

          </ul>
        </li>
        <li><a href="../../java/mail/index.html">Mail</a>
          <ul>
                <li><a href="../../java/mail/overview.html">Overview</a></li>
    <li><a href="../../java/mail/usingjavamail.html">Using JavaMail</a></li>
    <li><a href="../../java/javadoc/com/google/appengine/api/mail/package-summary.html">Low-level API</a></li>

          </ul>
        </li>
        <li><a href="../../java/images/index.html">Images</a>
          <ul>
                <li><a href="../../java/images/overview.html">Overview</a></li>
    <li><a href="../../java/javadoc/com/google/appengine/api/images/package-summary.html">API Reference</a></li>

          </ul>
        </li>
        <li><a href="../../java/users/index.html">Google Accounts</a>
          <ul>
                <li><a href="../../java/users/overview.html">Overview</a></li>
    <li><a href="../../java/javadoc/com/google/appengine/api/users/package-summary.html">API Reference</a></li>

          </ul>
        </li>
      </ul>
    </li>
    <li><a href="../../java/javadoc/index.html">Javadoc Reference</a></li>
    <li><a href="../../java/jrewhitelist.html">JRE Class White List</a></li>
    <li><a href="../../java/config/index.html">Configuration</a>
      <ul>
            <li><a href="../../java/config/webxml.html">Deployment Descriptor</a></li>
    <li><a href="../../java/config/appconfig.html">App Config</a></li>
    <li><a href="../../java/config/indexconfig.html">Index Config</a></li>
    <li><a href="../../java/config/cron.html">Scheduled Tasks</a></li>

      </ul>
    </li>
    <li><a href="../../java/tools/index.html">Tools</a>
      <ul>
            <li><a href="../../java/tools/devserver.html">Development Server</a></li>
    <li><a href="../../java/tools/uploadinganapp.html">Uploading and Managing</a></li>
    <li><a href="../../java/tools/eclipse.html">Google Plugin for Eclipse</a></li>
    <li><a href="../../java/tools/ant.html">Using Apache Ant</a></li>

      </ul>
    </li>
    <li><a href="../../java/howto/index.html">How-To</a>
      <ul>
              <li><a href="../../java/howto/unittesting.html">Unit Testing</a></li>

      </ul>
    </li>

    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Python</h2>
    <ul>
          <li><a href="../overview.html">Overview</a></li>
    <li><a href="../runtime.html">CGI Environment</a></li>
    <li><a href="index.html">Storing Data</a>
      <ul>
             <li><a href="overview.html">Overview</a></li>
     <li><a href="entitiesandmodels.html">Entities and Models</a></li>
     <li><a href="creatinggettinganddeletingdata.html">Creating, Getting and Deleting Data</a></li>
     <li><a href="keysandentitygroups.html">Keys and Entity Groups</a></li>
     <li><a href="queriesandindexes.html">Queries and Indexes</a></li>
     <li><a href="transactions.html">Transactions</a></li>
     <li><a href="typesandpropertyclasses.html">Types and Property Classes</a></li>
     <li><a href="gqlreference.html">GQL Reference</a></li>

     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="modelclass.html">Model</a></li>
         <li><a href="expandoclass.html">Expando</a></li>
         <li><a href="polymodelclass.html">PolyModel</a></li>
         <li><a href="propertyclass.html">Property</a></li>
         <li><a href="queryclass.html">Query</a></li>
         <li><a href="gqlqueryclass.html">GqlQuery</a></li>
         <li><a href="keyclass.html">Key</a></li>
         <li><a href="functions.html">Functions</a></li>
         <li><a href="exceptions.html">Exceptions</a></li>
       </ul>
     </li>

      </ul>
    </li>
    <li><a href="../apis.html">Services</a>
      <ul>
        <li><a href="../memcache/index.html">Memcache</a>
          <ul>
                 <li><a href="../memcache/overview.html">Overview</a></li>
      <li><a href="../memcache/usingmemcache.html">Using Memcache</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../memcache/clientclass.html">Client</a></li>
         <li><a href="../memcache/functions.html">Functions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../urlfetch/index.html">URL Fetch</a>
          <ul>
                 <li><a href="../urlfetch/overview.html">Overview</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../urlfetch/fetchfunction.html">The fetch Function</a></li>
         <li><a href="../urlfetch/responseobjects.html">Response Objects</a></li>
         <li><a href="../urlfetch/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../mail/index.html">Mail</a>
          <ul>
                 <li><a href="../mail/overview.html">Overview</a></li>
     <li><a href="../mail/sendingmail.html">Sending Mail</a></li>
     <li><a href="../mail/attachments.html">Attachments</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../mail/emailmessageclass.html">EmailMessage</a></li>
         <li><a href="../mail/emailmessagefields.html">Message Fields</a></li>
         <li><a href="../mail/functions.html">Functions</a></li>
         <li><a href="../mail/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../images/index.html">Images</a>
          <ul>
                 <li><a href="../images/overview.html">Overview</a></li>
     <li><a href="../images/installingPIL.html">Installing PIL</a></li>
     <li><a href="../images/usingimages.html">Using the Images API</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../images/imageclass.html">Image</a></li>
         <li><a href="../images/functions.html">Functions</a></li>
         <li><a href="../images/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../users/index.html">Google Accounts</a>
          <ul>
                 <li><a href="../users/overview.html">Overview</a></li>
     <li><a href="../users/userobjects.html">User Objects</a></li>
     <li><a href="../users/loginurls.html">Login URLs</a></li>
     <li><a href="../users/adminusers.html">Admin Users</a></li>

     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../users/userclass.html">User</a></li>
         <li><a href="../users/functions.html">Functions</a></li>
         <li><a href="../users/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
      </ul>
    </li>
    <li><a href="../config/index.html">Configuration</a>
      <ul>
            <li><a href="../config/appconfig.html">App Config</a></li>
    <li><a href="../config/indexconfig.html">Index Config</a></li>
    <li><a href="../config/cron.html">Scheduled Tasks</a></li>

      </ul>
    </li>
    <li><a href="../tools/index.html">Tools</a>
      <ul>
            <li><a href="../tools/devserver.html">Development Server</a></li>
    <li><a href="../tools/uploadinganapp.html">Uploading and Managing</a></li>
    <li><a href="../tools/uploadingdata.html">Uploading Data</a></li>
    <li><a href="../tools/webapp/index.html">webapp Framework</a>
      <ul>
             <li><a href="../tools/webapp/overview.html">Overview</a></li>
     <li><a href="../tools/webapp/running.html">Running the Application</a></li>
     <li><a href="../tools/webapp/requesthandlers.html">Request Handlers</a></li>
     <li><a href="../tools/webapp/requestdata.html">Request Data</a></li>
     <li><a href="../tools/webapp/buildingtheresponse.html">Building the Response</a></li>
     <li><a href="../tools/webapp/redirects.html">Redirects, Headers and Status Codes</a></li>
     

     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../tools/webapp/requestclass.html">Request</a></li>
         <li><a href="../tools/webapp/responseclass.html">Response</a></li>
         <li><a href="../tools/webapp/requesthandlerclass.html">RequestHandler</a></li>
         <li><a href="../tools/webapp/wsgiapplicationclass.html">WSGIApplication</a></li>
         <li><a href="../tools/webapp/utilmodule.html">Utility Functions</a></li>
         
       </ul>
     </li>

      </ul>
    </li>
    <li><a href="../tools/libraries.html">Third-party Libraries</a></li>

      </ul>
    </li>
    <li><a href="../howto/index.html">How-To</a>
      <ul>
              <li><a href="../howto/usinggdataservices.html">Google Data Services</a></li>

      </ul>
    </li>

    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Managing Your App</h2>
    <ul>
      <li><a href="../../theadminconsole.html">The Admin Console</a></li>
      <li><a href="../../quotas.html">Quotas</a></li>
      <li><a href="../../billing.html">Billing</a></li>
    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Resources</h2>
    <ul>
      <li><a href="../../../kb/index.html">FAQ</a></li>
      <li><a href="../../../articles/index.html">Articles</a></li>
      <li><a href="http://appengine-cookbook.appspot.com/">Cookbook</a></li>
      <li><a href="http://appgallery.appspot.com/">App Gallery</a></li>
      <li><a href="http://code.google.com/p/googleappengine/">SDK Code</a></li>
      <li><a href="http://code.google.com/p/google-app-engine-samples/">Sample Apps Code</a></li>
      <li><a href="../../../community.html">Discussion Groups</a></li>
    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><a href="../../roadmap.html">Product Roadmap</a></li>
  <li><a href="http://code.google.com/p/googleappengine/wiki/SdkReleaseNotes">Release Notes</a></li>
  <li><a href="../../revision_history.html">Revision History</a></li>
</ul>

        <a class="hidden" href="#gc-topnav-anchor">More Google App Engine resource links</a>
      </div>

      <div class="g-unit" id="gc-pagecontent">
        <h1 class="page_title">The Model Class</h1>



<p>The Model class is the superclass for data model definitions.</p>

<p><code>Model</code> is provided by the <code>google.appengine.ext.db</code> module.</p>

<ul>
  <li><a href="#Introduction">Introduction</a></li>
  <li><a href="#Model">Model()</a></li>
  <li>Class methods:
    <ul>
      <li><a href="#Model_get">Model.get()</a></li>
      <li><a href="#Model_get_by_id">Model.get_by_id()</a></li>
      <li><a href="#Model_get_by_key_name">Model.get_by_key_name()</a></li>
      <li><a href="#Model_get_or_insert">Model.get_or_insert()</a></li>
      <li><a href="#Model_all">Model.all()</a></li>
      <li><a href="#Model_gql">Model.gql()</a></li>
      <li><a href="#Model_kind">Model.kind()</a></li>
      <li><a href="#Model_properties">Model.properties()</a></li>
    </ul>
  </li>
  <li>Instance methods:
    <ul>
      <li><a href="#Model_key">key()</a></li>
      <li><a href="#Model_put">put()</a></li>
      <li><a href="#Model_delete">delete()</a></li>
      <li><a href="#Model_is_saved">is_saved()</a></li>
      <li><a href="#Model_parent">parent()</a></li>
      <li><a href="#Model_parent_key">parent_key()</a></li>
      <li><a href="#Model_to_xml">to_xml()</a></li>
    </ul>
  </li>
  <li><a href="#Disallowed_Property_Names">Disallowed Property Names</a></li>
</ul>

<h2 id="Introduction">Introduction</h2>

<p>An application defines a data model by defining a class that subclasses Model.  Properties of the model are defined using class attributes and <a href="propertyclass.html">Property</a> class instances.  For example:</p>

<pre class="prettyprint">
class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)
</pre>

<p>An application creates a new data entity by instantiating a subclass of the Model class.  Properties of an entity can be assigned using attributes of the instance, or as keyword arguments to the constructor.</p>

<pre class="prettyprint">
s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")
</pre>

<p>The name of the model sub-class is used as the name of the datastore entity kind.  The names of the attributes are used as the names of the corresponding properties on an entity.  Model instance attributes whose names begin with an underscore (<code>_</code>) are ignored, so your application can use such attributes to store data on a model instance that isn't saved to the datastore.</p>

<p>The datastore and the model class API impose several restrictions on property names and model instance attributes.  See <a href="#Disallowed_Property_Names">Disallowed Property Names</a> for a complete description.</p>

<p>A data entity can have an optional parent entity.  Parent-child relationships form entity groups, which are used to control transactionality and data locality in the datastore.  An application creates a parent-child relationship between two entities by passing the parent entity to the child entity's constructor, as the <span class="argname">parent</span> argument.  For more information about parents and ancestors, see <a href="keysandentitygroups.html">Keys and Entity Groups</a>.</p>

<p>Every entity has a key, a unique identifier that represents the entity.  An entity can have an optional key name, a string unique across entities of the given kind.  The entity's kind and name can be used with the <a href="keyclass.html#Key_from_path">Key.from_path()</a> and <a href="#Model_get_by_key_name">Model.get_by_key_name()</a> methods to retrieve the entity.  For more information about keys, see <a href="keysandentitygroups.html">Keys and Entity Groups</a>.</p>

<p>The method <a href="#Model_get_or_insert">Model.get_or_insert()</a> can be used to retrieve an entity that may not exist, creating it in the datastore if necessary:

<pre class="pretty print">
keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")
</pre>

<p class="note"><b>Note:</b> A Model instance does not have a corresponding entity in the datastore until it is <a href="#Model_put">put()</a> for the first time, either explicitly so or via <a href="#Model_get_or_insert">Model.get_or_insert()</a>.</p>

<p>The Model class is provided by the <code>google.appengine.ext.db</code> package.</p>


<h2>Constructor</h2>

<p>The constructor of the Model class is defined as follows:</p>

<dl class="apireference">
  <dt id="Model"><span class="type">class</span>&nbsp;<span class="itemname">Model</span>(<span class="argname">parent</span>=<span class="argdefault">None</span>, <span class="argname">key_name</span>=<span class="argdefault">None</span>, **<span class="argname">kwds</span>)</dt>
  <dd>
    <p>The superclass for data model definitions.</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">parent</span></dt>
      <dd>The Model instance or Key instance for the entity that is the new entity's parent.</dd>

      <dt><span class="argname">key_name</span></dt>
      <dd>
        <p>The name for the new entity.  The name becomes part of the primary key.  If <code>None</code>, a system-generated ID is used for the key.</p>
        <p>The value for <span class="argname">key_name</span> must not start with a number, and must not be of the form <code>__*__</code>.  If your application uses user-submitted data as datastore entity key names (such as an email address), the application should sanitize the value first, such as by prefixing it with a known string like "key:", to meet these requirements.</p>
        <p>A <code>key_name</code> is stored as a Unicode string, with <code>str</code> values converted as ASCII text.</p>
      </dd>

      <dt>**<span class="argname">kwds</span></dt>
      <dd>Initial values for the instance's properties, as keyword arguments.  Each name corresponds with an attribute defined on the Model class.</dd>
    </dl>
  </dd>
</dl>


<h2>Class Methods</h2>

<p>The Model class provides the following class methods:</p>

<dl class="apireference">

  <dt id="Model_get"><span class="itemname">Model.get</span>(<span class="argname">keys</span>)</dt>
  <dd>
    <p>Gets the model instance (or instances) for the given <a href="keyclass.html">Key</a> objects.  The keys must represent entities of the model's kind.  If a provided key is not of the correct kind, a <code>KindError</code> is raised.</p>
    <p>This method is similar to the <a href="functions.html#get">db.get()</a> function, with additional type checking.</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">keys</span></dt>
      <dd>A <a href="keyclass.html">Key</a> object or a list of <a href="keyclass.html">Key</a> objects.  Can also be a string version of a Key object, or list of strings.</dd>
    </dl>
  </dd>

  <dt id="Model_get_by_id"><span class="itemname">Model.get_by_id</span>(<span class="argname">ids</span>, <span class="argname">parent</span>=<span class="argdefault">None</span>)</dt>
  <dd>
    <p>Gets the model instance (or instances) for the given numeric ID (or IDs).</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">ids</span></dt>
      <dd>A numeric entity ID, or a list of numeric entity IDs.</dd>
      <dt><span class="argname">parent</span></dt>
      <dd>The parent entity for the requested entities, as a <a href="modelclass.html">Model</a> instance or <a href="keyclass.html">Key</a> instance, or <code>None</code> (the default) if the requested entities do not have a parent.  Multiple entities requested by one call must all have the same parent.</dd>
    </dl>
    <p>If <span class="argname">ids</span> is a string representing one name, then the method returns the model instance for the name, or <code>None</code> if the entity doesn't exist.  If <span class="argname">ids</span> is a list, the method returns a list of model instances, with a <code>None</code> value when no entity exists for a corresponding Key.</p>
  </dd>

  <dt id="Model_get_by_key_name"><span class="itemname">Model.get_by_key_name</span>(<span class="argname">key_names</span>, <span class="argname">parent</span>=<span class="argdefault">None</span>)</dt>
  <dd>
    <p>Gets the model instance (or instances) for the given key name (or names).</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">key_names</span></dt>
      <dd>A key name, or a list of key names.</dd>
      <dt><span class="argname">parent</span></dt>
      <dd>The parent entity for the requested entities, as a <a href="modelclass.html">Model</a> instance or <a href="keyclass.html">Key</a> instance, or <code>None</code> (the default) if the requested entities do not have a parent.  Multiple entities requested by one call must all have the same parent.</dd>
    </dl>
    <p>If <span class="argname">key_names</span> is a string representing one name, then the method returns the model instance for the name, or <code>None</code> if the entity doesn't exist.  If <span class="argname">key_names</span> is a list, the method returns a list of model instances, with a <code>None</code> value when no entity exists for a corresponding Key.</p>
  </dd>

  <dt id="Model_get_or_insert"><span class="itemname">Model.get_or_insert</span>(<span class="argname">key_name</span>, **<span class="argname">kwds</span>)</dt>
  <dd>
    <p>Get or create an entity of the model's kind with the given key name, using a single transaction.  The transaction ensures that if two users attempt to get-or-insert the entity with the given name simultaneously, then both users will have a model instance that refers to the entity, regardless of which process created it.</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">key_name</span></dt>
      <dd>The name for the key of the entity</dd>
      <dt>**<span class="argname">kwds</span></dt>
      <dd>Keyword arguments to pass to the model class if an instance with the specified key name doesn't exist.  The <span class="argname">parent</span> argument is required if the desired entity has a parent.</dd>
    </dl>
    <p>The method returns an instance of the model class that represents the requested entity, whether it existed or was created by the method.  As with all datastore operations, this method can raise a <a href="exceptions.html#TransactionFailedError">TransactionFailedError</a> if the transaction could not be completed.</p>
  </dd>

  <dt id="Model_all"><span class="itemname">Model.all</span>(<span class="argname">keys_only</span>=<span class="argdefault">False</span>)</dt>
  <dd>
    <p>Returns a <a href="queryclass.html">Query</a> object that represents all entities for the kind corresponding to this model.  Methods on the Query object can apply filters and sort orders to the query before it is executed.  See <a href="queryclass.html">Query</a> for more information</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">keys_only</span></dt>
      <dd>
        <p>Whether the query should return full entities or just keys. Queries that return keys are <a href="queriesandindexes.html#Queries_on_Keys">faster and cost less CPU</a> than queries that return full entities.</p>
      </dd>
    </dl>
  </dd>
  
  <dt id="Model_gql"><span class="itemname">Model.gql</span>(<span class="argname">query_string</span>, *<span class="argname">args</span>, **<span class="argname">kwds</span>)</dt>
  <dd>
    <p>Performs a GQL query over instances of this model.</p>
    <p>Arguments:</p>
    <dl>
      <dt><span class="argname">query_string</span></dt>
      <dd>The part of the GQL query following <code>SELECT * FROM <i>model</i></code> (which is implied by using this class method).</dd>
      <dt>*<span class="argname">args</span></dt>
      <dd>Positional parameter bindings, similar to the <a href="gqlqueryclass.html">GqlQuery</a> constructor.</dd>
      <dt>**<span class="argname">kwds</span></dt>
      <dd>Keyword parameter bindings, similar to the <a href="gqlqueryclass.html">GqlQuery</a> constructor.</dd>
    </dl>

    <pre class="prettyprint">
s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")
</pre>
    <p>The return value is a <a href="gqlqueryclass.html">GqlQuery</a> object, which can be used to access the results.</p>
  </dd>

  <dt id="Model_kind"><span class="itemname">Model.kind</span>()</dt>
  <dd>Returns the kind of the model, usually the name of the Model subclass.</dd>

  <dt id="Model_properties"><span class="itemname">Model.properties</span>()</dt>
  <dd>Returns a dictionary of all of the properties defined for this model class.</dd>

</dl>


<h2>Instance Methods</h2>

<p>Model instances have the following methods:</p>

<dl class="apireference">

  <dt id="Model_key"><span class="itemname">key</span>()</dt>
  <dd>
    <p>Returns the datastore <a href="keyclass.html">Key</a> for this model instance.</p>
    <p>A model instance does not have a key until it is <a href="#Model_put">put()</a> in the datastore.  Calling <span class="itemname">key()</span> before the instance has a key raises a <a href="exceptions.html#NotSavedError">NotSavedError</a>.</p>
  </dd>

  <dt id="Model_put"><span class="itemname">put</span>()</dt>
  <dd>
    <p>Stores the model instance in the datastore.  If the model instance is newly created and has never been stored, this method creates a new data entity in the datastore.  Otherwise, it updates the data entity with the current property values.</p>
    <p>The method returns the <a href="keyclass.html">Key</a> of the stored entity.</p>
  </dd>

  <dt id="Model_delete"><span class="itemname">delete</span>()</dt>
  <dd>
    <p>Deletes the model instance from the datastore.  If the instance has never been <a href="#Model_put">put()</a>, the delete raises a <a href="exceptions.html#NotSavedError">NotSavedError</a>.</p>
  </dd>
  
  <dt id="Model_is_saved"><span class="itemname">is_saved</span>()</dt>
  <dd>
    <p>Returns <code>True</code> if the model instance has been <a href="#Model_put">put()</a> into the datastore at least once.</p>
    <p>This method only checks that the instance has been stored at least once since it was created.  It does <i>not</i> check if the instance's properties have been updated since the last time it was <a href="#Model_put">put()</a>.</p>
  </dd>
  
  <dt id="Model_dynamic_properties"><span class="itemname">dynamic_properties</span>()</dt>
  <dd>
    <p>Returns a list of the names of all of the dynamic properties defined for this model instance.  This only applies to instances of <a href="expandoclass.html">Expando</a> classes.  For non-Expando model instances, this returns an empty list.</p>
  </dd>

  <dt id="Model_parent"><span class="itemname">parent</span>()</dt>
  <dd>
    <p>Returns a model instance for the parent entity of this instance, or <code>None</code> if this instance does not have a parent.</p>
  </dd>
  
  <dt id="Model_parent_key"><span class="itemname">parent_key</span>()</dt>
  <dd>
    <p>Returns the <a href="keyclass.html">Key</a> of the parent entity of this instance, or <code>None</code> if this instance does not have a parent.</p>
  </dd>

  <dt id="Model_to_xml"><span class="itemname">to_xml</span>()</dt>
  <dd>
    <p>Returns an XML representation of the model instance.</p>
    <p>Property values conform to the <a href="http://www.atomenabled.org/developers/syndication/">Atom</a> and <a href="http://code.google.com/apis/gdata/common-elements.html">GData</a> specifications.</p>
  </dd>
  
</dl>


<h2 id="Disallowed_Property_Names">Disallowed Property Names</h2>

<p>The datastore and its API impose several restrictions on names for entity properties and model instance attributes.</p>

<p>The datastore reserves all property names that begin and end with two underscores (<code>__*__</code>).  A datastore entity cannot have a property with such a name.</p>

<p>The Python model API ignores all attributes on a <a href="#Model">Model</a> or <a href="expandoclass.html">Expando</a> that begin with an underscore (<code>_</code>).  Your application can use these attributes to associate data with the model objects that is not saved to the datastore.</p>

<p>Lastly, the Python model API uses object attributes to define properties of a model, and by default the datastore entity properties are named after the attributes.  Because the <a href="#Model">Model</a> class has several properties and methods for other purposes, those attributes cannot be used for properties in the Python API.  For example, a Model cannot have a property accessed with the attribute <code>key</code>.</p>

<p>However, a property can specify a different name for the datastore than the attribute name by giving a <span class="argname">name</span> argument to the property constructor.  This allows the datastore entity to have a property name similar to a reserved attribute in the <a href="#Model">Model</a> class, and use a different attribute name in the class.</p>

<pre class="prettyprint">
class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")
</pre>

<p>The following attribute names are reserved by the <a href="#Model">Model</a> class in the Python API:</p>

<table class="columns">
  <tr>
    <td>
      <ul>
        <li><code>all</code></li>
        <li><code>app</code></li>
        <li><code>copy</code></li>
        <li><code>delete</code></li>
        <li><code>entity</code></li>
        <li><code>entity_type</code></li>
        <li><code>fields</code></li>
        <li><code>from_entity</code></li>
        <li><code>get</code></li>
        <li><code>gql</code></li>
        <li><code>instance_properties</code></li>
      </ul>
    </td>
    <td>
      <ul>
        <li><code>is_saved</code></li>
        <li><code>key</code></li>
        <li><code>key_name</code></li>
        <li><code>kind</code></li>
        <li><code>parent</code></li>
        <li><code>parent_key</code></li>
        <li><code>properties</code></li>
        <li><code>put</code></li>
        <li><code>setdefault</code></li>
        <li><code>to_xml</code></li>
        <li><code>update</code></li>
      </ul>
    </td>
  </tr>
</table>



      </div><!-- end gc-pagecontent -->
   </div><!-- end gooey wrapper -->

    </div> <!-- end codesite content -->

<div id="gc-footer" dir="ltr">
  <div class="text">
    
      <div class="notice"><div id="notice" style="text-align: center; border: 1em 0em 1em 0em">
  Except as otherwise <a
  href="http://code.google.com/policies.html#restrictions">noted</a>,
  the content of this page is licensed under the <a rel="license"
  href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
  Attribution 2.5 License</a>, and code samples are licensed under the
  <a rel="license" href="http://www.apache.org/licenses/LICENSE-2.0">Apache
  2.0 License</a>.
<!-- <rdf:RDF xmlns="http://web.resource.org/cc/" 
              xmlns:dc="http://purl.org/dc/elements/1.1/"
              xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  <Work rdf:about="">
    <license rdf:resource="http://creativecommons.org/licenses/by/2.5/" />
  </Work>
  <License rdf:about="http://creativecommons.org/licenses/by/2.5/">
    <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
    <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
    <requires rdf:resource="http://web.resource.org/cc/Notice"/>
    <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
    <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
  </License>
</rdf:RDF> -->
</div>
Java is a registered trademark of Sun Microsystems, Inc.</div>
    
    &copy;2009 Google -
    <a href="http://code.google.com">Code Home</a> -
    <a href="http://www.google.com/accounts/TOS">Terms of Service</a> -
    <a href="http://www.google.com/privacy.html">Privacy Policy</a> -
    <a href="http://code.google.com/more">Site Directory</a>
    <br /> <br />
    Google Code offered in:
    <a href="http://code.google.com/intl/en">English</a> -
    <a href="http://code.google.com/intl/es">Español</a> -
    <a href="http://code.google.com/intl/ja">日本語</a> -
    <a href="http://code.google.com/intl/ko">한국어</a> -
    <a href="http://code.google.com/intl/pt-BR">Português</a> -
    <a href="http://code.google.com/intl/ru">Pусский</a> -
    <a href="http://code.google.com/intl/zh-CN">中文(简体)</a> -
    <a href="http://code.google.com/intl/zh-TW">中文(繁體)</a>
  </div>
</div><!-- end gc-footer -->

</div><!-- end gc-containter -->

<script type="text/javascript">CODESITE_CSITimer['load'].tick('ats');</script>
<script src="../../../../js/codesite_tail.pack.04102009.js" type="text/javascript"></script>






  </body>
</html>


